fix(cli): os explain query teaches where / orderBy, and the catalog sweep asserts key retention - #17263

Fixes #16925

Clause-②: no

os explain query documented two keys QuerySchema does not have. Both faces of
the entry now read the schema's own spellings, and the #14811 catalog sweep grows
the assertion that can actually see this failure mode.

The defect, measured at origin/main

BaseQuerySchema (packages/spec/src/data/query.zod.ts) is a plain z.object,
so an unknown top-level key is dropped, not refused. The shipped example was
therefore green through the sweep and empty in the result:

declared example keys: [ 'object', 'fields', 'filters', 'sort', 'limit' ]
parses: true
output keys:           [ 'object', 'fields', 'limit' ]
DROPPED:               [ 'filters', 'sort' ]

An author who copied it got a query that parsed clean and ran with no filter and
no ordering — with limit: 50 sitting next to it, a different set of rows under
an ordinary success, and nothing in the output saying so.

Half 1 — the entry, both faces

The real shapes were read off BaseQuerySchema directly, not inferred from the
old Filter[] / SortConfig[] type names:

• where takes FilterConditionSchema — one condition tree, not an
  array. A field-keyed entry is a condition on that field (a bare value is
  implicit equality, an object is a map of $ operators), and $and / $or /
  $not combine conditions.
• orderBy takes SortNodeSchema[], whose direction key is spelled
  order. direction is not a synonym — SortNodeSchema is strict and
  refuses it by name, because when it was merely stripped, order fell back to
  its asc default and a descending request came back ascending.

Both the example and the two optional-table rows were corrected. Verified by
parse, on the corrected literal:

parses: true
output keys: [ 'object', 'fields', 'where', 'orderBy', 'limit' ]  DROPPED: []
orderBy roundtrip: [{"field":"created_at","order":"desc"}]

Half 2 — the sweep grows a key-retention assertion

The #14811 sweep asserts safeParse(...).success === true, and a silent strip
keeps that true — the green over this entry was false by construction. The
new assertion is the one that can see it: an example must parse and come back
with every key it declares.

It lands as a ratchet, not as a patch over a large hole. All nine BOUND
entries were re-measured against spec for this PR by feeding each schema an
unknown top-level key:

object     ObjectSchema       -> REJECTS unknown key
field      FieldSchema        -> REJECTS unknown key
view       ViewSchema         -> REJECTS unknown key
flow       FlowSchema         -> REJECTS unknown key
agent      AgentSchema        -> REJECTS unknown key
app        AppSchema          -> REJECTS unknown key
query      QuerySchema        -> SILENT-STRIP  (success: true, probe key retained: false)
dashboard  DashboardSchema    -> REJECTS unknown key
action     ActionSchema       -> REJECTS unknown key

Class size is 1 of 9, and the direction of travel is closing — the open top
level is declared deliberate and already owned (query.zod.ts: 「Deliberately NOT taken here: BaseQuerySchema's own top level stays non-strict. That is
#4001's to schedule.」). So the assertion is green across the whole catalog
the day it lands; what it defends is the day a bound entry resolves to an open
top level again.

It covers the EXAMPLE face only, deliberately. evaluate(key) reads
catalog[key].example and has never read the optional / required tables —
and this card's two wrong spellings lived on both faces. Covering the table
face is not a stricter version of this assertion but a different one, and the
measurement says why: a table row is prose, not a key. Measured across the nine
entries, rows that are not a key of their schema:

view       rows-not-a-key: ["list | form | listViews | formViews"]   (prose, correct as written)
action     shape NOT INTROSPECTABLE through the actionObject() wrapper
every other entry (query included, after this PR): []

So a table-face assertion needs a way to tell a key name from a description, and
a second technique for the one entry whose shape it cannot read. That is a design
decision rather than a mechanical extension, so it is declared as a gap in the
test's own header and raised as an open question rather than half-built here.

Ablation — predictions written before any leg ran

Recorded in full before the first leg. Restore the pre-fix filters / sort
spellings in the example and re-run; the contrast is the whole card.

No prediction came out wrong. The mutation was proven on disk before the run —
occurrence counts moved (where anchor 1 to 0, filters anchor 0 to 1) and the
blob hash moved off HEAD's 09ab4c72… to 6f8c85f5…; the restore was
git checkout HEAD -- ABSPATH (never bare), proven by blob equality,
git diff HEAD at 0 bytes and a clean git status --porcelain, all under a
trap ... EXIT INT TERM with absolute paths. No build leg is involved: the test
imports ../src/commands/explain by relative path, so the mutation reaches the
run from source.

Verification

• pnpm --filter @objectstack/cli exec vitest run --project unit — 190 files,
  2644 passed. The integration tier is declared to CI: this diff touches no
  spawn entry, no bin/, and no test/helpers/serve-process.ts.
• pnpm --filter '@objectstack/cli^...' build — dependency closure green;
  pnpm --filter @objectstack/cli build green (two published-subpath pins read
  the package's own dist/ and exit loudly without it — a prerequisite, not a
  finding).
• pnpm --filter @objectstack/cli typecheck — reported below.
• Gate family derived on the final tree with
  node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack
  and reconciled with --ran: 61 commands, 58 exit 0. Every exit code was
  captured by redirect-then-$?, never through a pipe.

Docs-drift round

Run on the final head. scripts/docs-audit/affected-docs.mjs named 15 candidate
pages; none carries the wrong spelling at query level — the hand-written docs were
already correct and os explain was the outlier (content/docs/data-modeling/queries.mdx:22-23
is the corrected shape verbatim). The four pages a prose-class sweep turns up for
filters: / sort: are all a different surface (a nav item's filters, a
single view's sort), and content/docs/ui/react-pages.mdx already documents the
silent-drop behaviour this change makes more true, correctly, with no edit owed.
Positive control for the sweep pattern: 2 hits in content/docs/ui/views.mdx and 2
in explain.ts at origin/main. Nothing under docs/ (which the tool never walks)
carries the shape either. No page edited; ⛔ nothing under content/docs/releases/**
was touched.

Acceptance notes / 验收备注

Noted, not filed — none of these is a reproducible defect, a contract violation, or
an authoring trap:

• Triage's parenthetical about view's optional table does not hold on today's
  tree. view's optional rows are name / label / object and its required
  row is the slot row — no filters / sort rows. The two spellings appear in
  view's prose (a line comment and the container description), where they
  correctly describe a single view's keys one level down. The fence was honoured
  regardless: view is untouched, and its example remains [finding] os explain view's example teaches a flat view literal — ViewSchema is a CONTAINER (list / form / listViews / formViews) #15171's.
• Inside that same fenced prose, the line comment spells filters where the entry
  description spells filter. An observation about a comment on another card's
  entry — not filed, not edited.
• query's optional table lists six of QuerySchema's seventeen keys — search,
  searchFields, top, aggregations, groupBy, having and expand are absent.
  Missing members are an omission, not an error, and out of this card's scope.
• Three gates in the derived family exited 3 (PREREQUISITE NOT MET) on the first
  sweep, none of them a finding; re-run after a full build, reported in the dev report.

Fences honoured

• ⛔ packages/spec untouched — the open top level stays 未知键静默剥离仍是全仓默认:把 #3405 的 strict 收紧从一个 schema 推广到整个可授权面(ADR-0078 完整性闸门) #4001's. The diff is
  packages/cli/src/commands/explain.ts, packages/cli/test/commands.test.ts and
  one changeset.
• ⛔ view not edited. ⛔ No accept set relaxed, no public face widened: the schema
  did not move, only the catalog entry that misdescribed it.

Generated by Claude Code